A macro is a block of text or HTML that is defined in a single place which may then be used repeatedly in any of your cloaked documents. This gives you the ability to create a section of HTML text once and then use it repeatedly on many different pages on your server.

For example, many organizations put the same header and footer information on every page of their server. This helps to maintain a consistent look and feel and to make sure that navigational links to the home page, help, or other pages of interest are always available. Using macros, the header and footer can be defined once in a single place and then used on all pages. This makes it easier to create new pages and makes updating the header and footer very quick and simple.

Macros can even contain other macros, or can be used to include entire HTML files inside of an HTML page.

There are two steps in using macros: defining the macros and then using them in your documents. Neither step is complicated...

Defining Macros

Begin by creating a file called "NetCloak.macros" in the "NetCloak Files" folder. This will be a standard text file, so use a text editor of your choice. Even SimpleText will do.

Once the file is open, make sure it is blank and you are ready to create a macro. Use the command <BEGIN_MACRO name> to start each macro, where "name" is the name of your macro. For example, if you want to create a standard header for your documents, you might start your macro with

     <BEGIN_MACRO Header>

Next, enter the HTML text you would like to be inserted when the macro is processed. You may enter as much or as little text as you like. When your macro is complete, end it with the <END_MACRO> command.

An example should make this clear:

     <BEGIN_MACRO NavigationLinks>     <HR>     <A HREF="http://192.1.2.3/Home.html">Go To Our Home Page</A>     <A HREF="http://192.1.2.3/Help.html">Get Help</A>     <HR>     <END_MACRO>

Whenever a cloaked document invokes this "NavigationLinks" macro, the text between the BEGIN_MACRO and END_MACRO commands will be inserted.

You may define as many macros in the "NetCloak.macros" file as you like, and is limited only by the available RAM allocated to NetCloak (or the Web server for the Plug-In version). Make sure that each macro you define has its own BEGIN_MACRO and END_MACRO commands.

Changing Macros

Like NetCloak aliased documents, the macro file is loaded into RAM when NetCloak is started and must be reloaded whenever you make a change. If you add or change a macro, you must have NetCloak reload all the macros. You can quit NetCloak and restart, but two additional methods are provided.

1. Choose "Reload Documents" from the "File" menu within the NetCloak ACGI. (This option is only available if you are using the NetCloak CGI, and won't work if you are cloaking using the NetCloak plug-in.)

2. Send the reload command from a web browser using the URL:

   http://your.server.com/NetCloak.acgi$RELOAD

   To perform a reload when using the plug-in version, use a URL of "RELOAD" with a "cloaked" suffix, as in:

   http://your.server.com/RELOAD.nclk

   You will note that the Reload command is the same one necessary to reload aliased documents cached in RAM. When you use Reload, both aliased documents and macros will be reloaded.

Using Macros

Any cloaked document can use any macro defined in your "NetCloak.macros" file. Wherever you want to use a macro, simply use the command <MACRO name>, where "name" is the name of the macro. For example, to use the macro defined above, the cloaked document might end with this HTML text:

     THANK YOU FOR VISITING OUR WEB SITE!
     <MACRO NavigationLinks>     </HTML>

At the bottom of this page, the links to the home page and to the help system would be displayed, just as if they had been put directly into the document.

The macro command can also be used to include entire files, in addition to HTML snippets defined in the "NetCloak.macros" file. In place of the macro name, simply specify a file name, including the path, where appropriate. For example:

     The file "Extra.html" looks like this:
     <P>     <MACRO Extra.html>

In this case, the entire "Extra.html" file will be inserted into the page.

Inserting entire files can be useful when you don't have enough memory to store all of your large macro in the "NetCloak.macros" file (since the entire file is held in RAM) or when the file being inserted is generated by some other application.

The Macro command will insert files located in the root folder hierarchy. If you would like to insert a file outside the root folder, make a Finder alias to the file and place the alias in the root folder or another folder contained within the root folder. As with aliases in the NetCloak.config file, pathnames must be relative to the root folder and start with a slash.

Note that if the Security setting 'Only process macros listed in "NetCloak.macros"' is enabled, you cannot use the MACRO command to insert the contents of arbitrary files into your cloaked pages. See the section entitled "Security" for more information.